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Preface 


THIS PRELIMINARY NOTE describes the Macintosh® operating 
system driver interface to the AppleTalk® Data Stream Protocol (ADSP), . 
which is a protocol that provides the client with a powerful interface to an 


AppleTalk network. 


What’s in this note 
This note is divided into two chapters and an appendix that contain the 
following information: 


m Chapter 1, “About AppleTalk Data Stream Protocol,” explains concepts 
and components used in ADSP. 


w Chapter 2, “ADSP Routines,” describes each ADSP function call, including 
parameter blocks and result codes, and provides a sample client program. 


m The Appendix, “Summary of ADSP Data Structures,” presents ADSP 
constants, data types, and assembly language information. 


Who should read this note 


This note is intended for software developers writing applications that use_ 
ADSP services. To understand and use this document, developers should be 
familiar with: 


m the Device Manager, described in Chapter 6 of Inside Macintosh, 
Volume II 


m the AppleTalk Manager, described in Chapter 10 of Inside 
Macintosh, Volume II 


Associated documents 
The following documents supplement the information in this-note: 


m the AppleTalk Data Stream Protocol Specification, which explains ADSP. in. 
detail (this information will be incorporated into the book, Inside 
AppleTalk) 


m Inside AppleTalk, which explains the AppleTalk protocols in detail: 


Chapter 1 About AppleTalk Data Stream Protocol 


THE APPLETALK® DATA STREAM PROTOCOL (ADSP) is a symmetric, 
connection-oriented protocol that guarantees the ordered delivery of full- 
duplex streams of bytes between two given sockets in an AppleTalk internet. 
ADSP is a client of the Datagram Delivery Protocol (DDP) and a peer to the 
AppleTalk Session Protocol (ASP). 


A connection is an association between two sockets that allows the reliable, 
full-duplex flow of data bytes between the sockets. A connection is 
composed of two connection ends, each of which is uniquely identified by its 


internet socket address and a connection identifier (also called a CID). 


The client can use ADSP to create and remove connection ends, to request 
connections with remote ends, to wait passively for connection requests 
from remote ends, to read and write on open connections, and to close 


connections. 


ADSP features include 


m a built-in flow-control mechanism, ensuring that a sender never sends 


bytes to a receiver with no buffer space 


= an end-of-message mechanism that enables the client to break streams of 


bytes into logical messages 


m attention messages that allow clients to signal each other outside the 


normal flow of data 


m a forward-reset mechanism that enables a sender to abort the delivery of 


all outstanding bytes sent to the remote client 


Using ADSP 


ADSP is implemented as a Macintosh® 6 operating sysiein driver. To use ADSP, the client must first 
initialize the AppleTalk Manager by opening €, MPP. driver and then initialize ADSP by opening the 
.DSP driver. : 


A Warning The client should never attempt to close .MPP or .DSP because other 
processes may be using these drivers. «a 


The Device Manager handles communication between the client and the ADSP driver. The 
control routine in the Device Manager is used to access ADSP functions; the client passes a different 
csCode for each function. ero ir ofseh sn 

ADSP provides a facility for building connection servers. A set of advanced calls enables a client 
to set up a connection listener to receive Open Connection requests from remote clients and to 
distribute these requests to other connection ends for further processing. 


Connection ends - 


The memory ADSP requires to maintain 4 connédtion end is provided by the client. To create a 
connection end, the. Client must allocate. a | connection control block (CCB), a send queue, a receive 
queue, and an attention message buffer for ADSP's intemal use. Pointers to the required memory 
are passed to ADSP i in'a control call with ‘csCode s set io 5 dspinit This call creates and initializes the 
connection end and returns a refnum that identifies the connection end in subsequent calls to 
ADSP. an re ae Se kx i ay) . 
we UD OR 
on bad s sngowas tb ale Geo! 
© Note: The memoty alloéated“arid patséd to-ADSP. to maintain a connection end becomes the 
exclusive property of ADSP. forthe. life 6f the connection end. The client must ensure that 
the memory remains locked! and Unaltered until-ADSP removes the connection end. 
go ore) mae 7 
The connection end. is initialized to a:closed state. A control call with csCode set to dspOpen is 
used to open a connection with a femote cgnnection end or to wait passively for a remote client to 
open a connection. The AppleTalk Name Binding Protocol (NBP) can be used to register a name for 
a connection end_or.cganection server and to. determine the addresses of other NBP-registered 


connections. meee cagppeng te 


Once a connection is, ‘open, the, client makes control calls to read data from or to write data to 
the remote connection end. ‘When the client no longer requires the connection, the control call 
dspClose returns the connection end to a closed state, and dspRemove closes the connection and 
deletes the connection end from ADSP’s internal data structures. The memory allocated for the 
connection end’s associated data structures can be released only after the dspRemove call has 
completed. 
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Connection control block — eer Ty 
“Desig 


Oy 
The CCB is a block of memory, allocated by the client, that ADSP uses to keep state. information a . 
about the connection end. Most of the CCB fields are for ADSP's ‘internal use and aré not visible to, rae - 
the client. The CCB must not be altered or moved in memory until ADSP is called to remove the”? * A et 
connection end. The CCB fields are as follows: 
Field Description oo ee 
ccbLink pointer to next CCB (for the exclusive use of ADSBY. a aioe dina 
refnum reference number of this CCB 
state current state of the connection end a . _ neat 
userFlags connection event flags for the client _ — ' 7 . a0) Aa coon 
localSocket DDP socket number for reading from and writing to this connection end»: » anu, dons 1! ty Q 
remoteAddress _ internet socket address of the remote connection’ ed” - a pots ashes vow dekh 
attnCode attention code of incoming attention message? °">*' > SE EE MAG be Gu 
attnSize size of incoming attention message aes a DSN ES 
attnPtr pointer to buffer for incoming attention messages 
reserved additional fields (for the exclusive use of ADSP) ~~ oe on 


bite movoenn 

The client must never alter CCB fields (with the exception of _ userFlags). Hi However, the c client may aeCk emer 
poll CCB fields to determine the state of the connection. we ” henT es 
The refnum field, a reference number for the connection ‘end, is ‘generated by ADSP when the —_ vas 


connection end is created. This refnum is used by the client ‘and ADSP te ton refer to the connection a2ct), _ 
Ty ILE NG eG mb “\ 4 See, 
end. 
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The client may poll the value of state to determine the current sta state of the cofinection end The 
possible states are listed in the Appendix, “Summary of ADSP Data Structures.” 

When an unsolicited event occurs on the connection end, ADSP sets an appropriate bit in the 
userFlags field of the CCB. The client tests the bits to determine what-occumed.'Events that cafemga1 sil! aM 
occur include receipt of an attention message, the receipt of a-fonward reset, the;closing of the racing: 6. 2K: 
connection by the remote end, or the tearing down of the connection becayse-the remnote-end Bas: sac. oc 
become unreachable. The client must clear the bits in the userFlags field after the corresponding 
event has been processed. 

The /ocalSocket field contains the DDP socket number through whic the tontiedtion ent 19 TOMLNTRO 2 
transmits and receives packets. The remoteAddress field contains the infemet Socket addréss eine BBQ 
remote connection end (if any). pr yard am. ASE SOWIE GO2 ED 

The attnPtr field points to the client buffer that is available t6° vcbtté itctn miseg from RUS 30 
the remote connection end. The atinSize field contains the size (in bytes) of any attention message anol of 


received from the remote client (from 0 to 570 bytes). The atinCode field contains thie clic: (909 20299 BSD 
definable code that was received. SEA Tan BOS Noe 309 ors 
BDO SC MUSA? aa) UIST Been 

‘Acace pms go 99n6 yo 3d 23) 

sunb yb procase eats a D9e 


, 
Pats Loy 
saa he ee AS 
4 
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User routines 


When creating a connection end, the client may specify the address of a user routine to be called 
whenever an unsolicited connection event occurs. Unsolicited connection events are those that do 
not occur as a direct result of a client control call, for instance, the receipt of an attention message 
or close advice from the remote end, or the tearing down of the connection because of a timeout. 
The various events are listed in the Appendix, “Summary of ADSP Data Structures.” 

The user routine is called with register Al pointing to the CCB of the connection end. By 
examining the fields of the CCB, the routine.can, determine the connection (from the refnum field), 
the event (by testing bits i in ‘the “userFlags field), and the resulting state of the connection (from 
the state field). If an attention message is received, the routine can access the message from the 
atinSize and atinPrtr fields. 


ctas 


@ Note: The user, routine is simiat to an 1 ioCompletion routine. It is called at interrupt level and 
must follow all rules regarding interrupt-level routines. Refer to the discussion of the Device 
Manager in Inside’ Macintosh, Volume tT TI; for’ details. If the limitations of an interrupt-level 
routine are unsuitable for your application, use the alternate method of periodically polling 
the userFlags field of the CCB for connection events. 
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THIS CHAPTER describes each of the ADSP functicl! calls and iis the efits Sf arts, nes 


a Tal ins. ne 
the parameter block affected by the call. It also identifies possible result, a ole: sty 
codes. sbeeabn oo: set?ah 


The number next to each parameter name indicates the byte offset of the 


parameter from the start of the parameter block ‘Pointed to by register AQ, “An ~ i ns 
B fay Ciddda 


arrow next to each parameter name indicates. ‘whether it's an input, output ,0F; .. < geagls 


input/output parameter: sey Pre. ge ee tuey 
a) pene Qhey see wih 

Arrow Meaning 

— parameter is passed to the routine 

<— parameter is returned by the routine 

<—> parameter is passed to and retumed by the routine 
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Create Connection End 


This call creates and initializes a connection end: The refnum of the CCB is retumed in the 
ccbRefNum parameter. The client can use this value to reference the connection end in subsequent 
calls to ADSP. The caller provides a pointer toa’ CCB in the parameter ccbPir. The CCB becomes the 
exclusive property 6f ADSP and must not be moved or altered until the client calls ADSP to remove 
the connection end. The client passes to userRoutine the address of a routine to be called in case of a 
connection event. 

An ADSP connection end requires buffer space to hold incoming and outgoing bytes. The send 
queue holds all bytes the client has asked ADSP to send over the connection whose delivery to the 
remove client has not yet been acknowledged. ‘The receive queue buffers bytes received from the 
remote end until the client is able to read them. These queues are allocated by the client and become 
the exclusive property of ADSP; the queues must not be altered or moved until the connection end 
is removed. Pointers to the queues are passed in the fields sendQueue and recuQueue. The two 
queue size variables (sendQSize, recuQSize) are used to pass the size (in bytes) of these client- 
supplied buffers. When allocating the queues, the client should determine the size using the 
following rule: 


m = queue size = desired size + (desired size / 8) + 1 


The atinPir parameter contains the address of a client-supplied buffer that receives attention 
messages from the remote connection end. The attention buffer should be the constant 
attnBufSize bytes in size. The buffer must remain locked until the connection end is removed. 

The localSocket parameter specifies the connection end's DDP socket. A value of 0 causes DDP 
to allocate a socket dynamically. The socket number is returned when the call completes. 


Parameter block —> 2% csCode word always dspInit 
<— 2 ccbRefNum = word __ returns refnum assigned to connection end 
—> ccbPtr long _ pointer to CCB 
—> 8 userRoutine long __ routine to call on connection events 
—> sendQSize word _ size in bytes of the send queue 
—> 4 sendQueue long _ pointer to send queue 
—> 8 recvQSize word _ size in bytes of the receive queue 
—> wf recvQueue long _— pointer to receive queue 
—> attnPtr long __— pointer to buffer for incoming attention 
messages 
<> § localSocket byte | DDP socket number for this connection end 


Result codes ddpSktErr error opening socket 


6 Create Connection End 
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Remove Connection End Per y 2 Og eo 
This call closes any open connection and removes the connection:end specified by the * ParaMEHET ery ley &. 


ccbRefNum. The DDP socket is closed if it is not in use by another Connection end. Upon .- "gros nae tev SRS 
completion of this call, the CCB, attention buffer, and queue resources are.no longer needed, aad ae qely creat 
memory can be released by the client. If the abort flag is nonzero, any, optstanding client, requests... Got yp mye tes 
on the connection end are aborted, and all data in the send queue is discarded, i. 
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wd FIED 8. 
Parameter block —> 2% csCode word always dspRemove oe + BONO 
> x ccbRefNum word —refnum of connection dai 2% ° eee : 
> # abort byte abort thé connection flag aE aes 
Jot ak ave 
Result codes errRefNum bad connection refnum- 7 Wt vate odd dine boo egy 
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Open Connection. a a “5 


This call is used to set the opening state for a connection end. The state of the connection end 
must initially be closed. The connection end. can be set into four opening states by setting the 
parameter ocMode to one of the following constants: ocRequest, ocPassive, ocAccept, ocEstablish. 

Open mode ocRequest specifies that ADSP should initiate opening a connection with the remote 
address specified in the parameter remoteAddress. The filterAddress parameter is used to filter 
connection ends responding to the Open Connection request. A 0 in the network number, node 
identifier,-of. socket number of filterAddress means that a connection can be established with any 
connection.end @n any network, node, or socket, respectively. Setting filterAddress to be the same 
as remoteAddress means that a connection will be established only with a connection end on the 
specified 7emotedddress, An ocRequest Open Connection call completes when a connection is 
established, -when-gn-Open Connection Denial is received from a remote end, or when the maximum 
retries have been exceeded. 

Open mode. ocPassive sets the connection end to a passive opening state. The connection end 
starts the copnection-opening dialog when an.Open Connection request is received from some 
remote connectign end. The filterAddress can be used to specify the remote addresses with which 
the connectign end,is willing to establish a connection. A 0 in the network number, node identifier, 
or socket number-of filferAddress means that a connection can be established with any connection 
end on any network, node, or socket, respectively. An ocPassive Open Connection call is not 
complete-until 4 valid. Open Connection request. is received from a remote connection end. When an 
Open Connection request is received, the connection end enters the opening state and completes in 
the same manner as in the ocRequest mode; : 

The third open mode, ocAccept, is used by connection servers to complete an open-connection 
dialog, establishing a connection with the remote address from which an Open Connection request 
had been received by the server's connection listener. The remoteAddress, remoteCID, sendSegq, 
sendWindow, and attnSendSeq parameters should be filled in using the respective parameters 
returned from the connection listener’s lister+équest (see “Listen For Connection Request” later in 
this chapter). An ocAccept Open Connection call completes in the same manner as in the ocRequest 
mode. 

With the last mode, ocEstablish, ADSP considers the connection end established and the 
connection state open. This mode allows two peer clients to establish their respective connection 
ends based on connection-opening information that has been negotiated outside of ADSP. It is the 
client’s responsibility to provide values for the parameters remoteCID, remoteAddress, sendSeaq, 
sendWindow, recuSeq, attnSendSeq, and attnRecuSeq. Get New CID should be called to assign a 
unique /oca/CID on the connection end prior to opening a connection in this fashion (see “Get New 
CID” later in this chapter). The ocEstablish Open Connection call completes immediately. 

The parameter oc/nterval specifies the interval between retransmission of Open Connection 
requests in 10-tick (1/6-second) increments. The client can set the interval to any value from 1 (1/6 
second) to 180 (30 seconds) inclusive. The default value of 6 (1 second) is used if the parameter is 0. 
This parameter should be specified for Open Connection modes ocRequest, ocPassive, and ocAccept. 


8 Open Cbithection 


The ocMaximum parameter specifies the total number of times-an-Gperi Connection Tequest is@* ° 
transmitted. Passing 0 for this parameter causes the default value of 3 to be used, but the elient Earl * Cy sul 
set the maximum to any value from 1 (only one Open Connection request is transmitted) to 255 . 
inclusive (continuously retransmit Open Connection requests until an acknowledgment or deriial is” 
received). This parameter should be specified for Open Connection modes ocRequest, ocPassive paid” 
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OcAccept ONC Marrs 
we Fe OG 7 
Parameter block —> 2% csCode word always dspOpen SOS NL OG, eI 
—_ 32 ccbkefNum word _ refnum of connection endj* 2! 272 2oWSaK 
<— localCID word connection identifier. of this Confedion end? 
<—> %*% remoteCID word — connection identifier of remoté c6finection” 
‘end: a QO ta Aten 
<—> 8 remoteAddress long ~ ‘internet address of remote corinection end - 
—> filterAddress long _filterrfor.incoming Opets Conieeten 22: iE, 
requests sp aed osneor 
<—> £ sendSeq long _initial'send sequence nuiiber-to tise? 1990 
<—> sendWindow word _ initial size-of remote-ehd’s recewe buffer! 27: 
—> + % recvSeq long _>inItial receive sequence numibert tsé 2° 21" 
<> % attnSendSeq long  %initial-attention send sequence -futAber?"°~ * 
—> attnRecvSeq long  - initial. attention receive sequéntétiutnber “>” 
—> & ocMode byte _coniiection-opéning modé 8 S80 YOE ODN 
—> 6 ocinterval byte . -interval between Open Corinéction Feqiets® o 
—> 6 ocMaximum byte -’maximum retries of Open Conriettion “2 © 
request - x H@k VS ST SMe. 2 
nope ve & it, 0 bard ony 
Result codes errRefNum bad connection refnum.. eR gnideI4LES sun 
errState connection end must be closed poo ae eed 2 
errOpening open connection attempt failed - “5 pe bog acest Wor 
errAborted request aborted by a dspRemove or * dspClose calheasqa yagi bow: 
WATTS pk weighs 2 


hy 

wey unborn id ff 
G9 ile GOL IAE 
Ge AG OBO 7 
Wodienc 3291 2 ic 

¥, sosggt yA 


ce me oo rn Vote 
aye wy aR OCD 


v ey me ae . z 
Seyi) AD! Ci oe 
mt tee tan ONCE ASF 
Jon Ounetge Oc) Gal OG) Bae 


yc ae bluc.ie “ste Tisiad » 


Open Connection. fie ? 


Close Connection 


This call closes any open connection and sets the state of the connection end to closed. If the abort 
flag is nonzero, any outstanding client requests on the connection end are aborted, and all data in 
the send queue is discarded. 


Parameter bloox i: -——> 2% csCode | :.. word always dspClose 
—>-—«s« O22 ccbRefNum word _ refnum of connection end 
—> abort byte abort the connection flag 
Result codes errRefNum bad connection refnum 
eC. 
19 PO OST 


10 Close Gofhnection 
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Create Connection Listener _ “ay 9) 


This call creates and initializes a connection listener. The caller provides a pointer to a CCB in the vee pene 


at 
tyke thw 4 


parameter ccbPtr. The CCB is used by ADSP to maintain the connection listener. The refnum of the hecetar 
CCB is returned in the ccbRefNum parameter. The client can use this value to reference the listengy i in 7 
subsequent calls to ADSP. - 

The localSocket parameter specifies the DDP socket the connection listener will use. Avalue. * 4 -tere: 


0 causes DDP to allocate a socket dynamically. The socket number ‘is retuned when the call 
completes. 


Parameter block -—> 2% csCode word ~=.always dspCLinit .4:-~ CO hea 
<— R22 ccbRefNum word __ returns refnum assigned to connection 
listener 
—> F¥ ccbPtr long _— pointer to CCB 
<> $8 localSocket byte | DDP socket number for this connection end 
Result codes ddpSktErr error opening socket 


Create Connection Listener: -.--. 11 


Remove Connection Listener 


This call closes the connection listener specified by refnum. If the abort flag is nonzero, any 
outstanding client requests (such as Deny Connection Request calls) are aborted. Upon completion 
of this call, the CCB is no longer needed, and the memory it occupied can be released. 


Parameter block -—> 2% csCode word always dspCLRemove 
i 7 ccbRefNum = word __refnum of connection listener 
“32 —p> ¥ abort byte abort the connection listener flag 
Result codes errRefNum bad connection refnum 
puke 
bh TOU 
ROUS 


12 Remove Connection Listener 


Listen For Connection Request 


Connection servers use this call to listen for connection requests. The caller specifies the refnum of 


the connection listener in the parameter ccbRefNum. The call completes when ADSP receives an, | 


Open Connection request, on the connection listener’s socket, that satisfies the address 


requirements specified in the filterAddress parameter. The client must then determine what to do 
with the connection request. If a connection can be opened, the client must call Open Connection . ¢ «ser: 
on an available connection end and set the ocAfode parameter to ocAccept. The values retumed in the 
parameters remoteCID, remoteAddress, sendSeq, sendWinsow, and attnSendSeq from the completed 
listener call should be passed in the respective parameters of the Open Connection call. If the 
request cannot be honored, the client should advise the remote end by calling Deny Connection > 
Request, specifying the listener’s ccbRefNum. 
Several listen requests can be posted to the connection listener, and each request can have a 
different filter address specification (if desired). 


Parameter block —> 4 
—> 22 
<— » 
<— 38 
— 42 
<— ££ 
<— 0 
<— °£ 

Result codes errRefNum 
errState 
errAborted 


csCode word always dspCLListen 

ccbRefNum — word __ refnum of connection end 

remoteCID word connection identifier of remote connection 
end 

remoteAddress long __ internet address of remote connection end 

filterAddress long filter for incoming Open Connection 
requests 

sendSeq long _ initial send sequence number to use 

sendWindow word _ initial size of remote end’s receive buffer 

attnSendSeq long _initial attention send sequence number to 
use 


bad connection refnum 
not a connection listener 
request aborted by a dspRemove call 


Listen For Connection Request... ~ 13 
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Deny Connection Request 


This call is used by the client of a connection listener to advise a remote end that an Open 
Connection request cannot be honored. The caller should specify the connection listener in the 
parameter ccbRefNum. The remoteC1D and remoteAddress parameters should be filled in using the 
corresponding values retumed from the completed listener call. 


Parameter block —> % 
—> 32 
—> %6 


muy asf? 


—> 38 


yO, y 
Result codes errRefNum 
errState 
errAborted 


14 Deny Connection Request 


csCode word always dspCLDeny 

ccbRefNum = word _ refnum of connection listener 

remoteCID word connection identifier of remote connection 
end 

remoteAddress long _ internet address of remote connection end 


bad connection refnum 
not a connection listener 
request aborted by a dspRemove call 


Get Status 


This call returns the current state of the connection end specified by the parameter ccbRefNum. 
Note that the values returned in the parameters sendQPending and recuQPending include any _ 
bytes taken up by logical end-of-message indicators. 


Parameter block -—> 2% 
—> 22 
<— x 
<— 8 
<— 4 
<— 42 
<— 44 
Result codes errRefNum 


csCode word 
ccbRefNum —_ word 
statusCCB long 

sendQPending word 
sendQFree word 
recvQPending word 
recvQFree word 


bad connection refnum 


always dspStatus 

refnum of connection end 
pointer to the CCB 

bytes waiting to be sent or acknowledged 
available buffer in bytes of send queue 
bytes waiting to be read from queue 
available buffer in bytes of receive queue 


Get Status 15 


Read Bytes 


This call is used by the client to read bytes sent by the remote connection end. The parameter 
reqCount specifies the size of the buffer (in bytes) into which data is to be read. The parameter 
actCount is set to the actual number of bytes read. The parameter dataPir points to a buffer that 
will receive the bytes. 

The call completes when the requested number of bytes have been read or an intervening logical 
end-of-message indicator is encountered. If the last byte read constitutes the end of a logical 
message, the parameter eom will be set to 1. 

If the connection is closed or torn down, outstanding read requests complete in the normal 
manner. Even though the connection is closed, bytes remaining in the receive queue are still valid 
data. The client may continue to post read requests to ADSP until there are no more bytes left in 
the receive queue to be read. The routine Get Status can be called to determine how many bytes 
remain, or read requests can be posted until the parameters actCount and eom both retum 0. If 
there are fewer than regCount bytes remaining in the receive queue, the read request completes 
with actCount set to the actual number of bytes being returned. 


@ Note: A remote connection end may close the connection immediately after sending a 
stream of bytes to the connection end. By polling the state or userFlags fields of the CCB, 
you may find that the connection has been closed before you have finished reading the 
bytes from ‘thé receive queue. You must decide whether to continue processing the bytes in 
the receive queue. 


bea 
Parameter block 


—> 2b csCode word always dspRead 
—> 2 ccbRefNum word __ refnum of connection end 
—> reqCount word requested number of bytes to be read 
< *%* actCount word actual number of bytes read 
—> 8 dataPtr long pointer to buffer into which bytes are to be 
read 
<— eom byte 1 if end of message, otherwise, 0 
Result codes errRefNum bad.connection refnum 
errFwdReset read terminated by forward reset 
errAborted request aborted by a dspRemove or dspClose call 
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Write Bytes 


This call is used to send data to the remote connection end. The refnum field specifies the 


connection end from which the data is sent. The parameter reqCount specifies the number of bytes 
to be copied to the send queue, while actCount returns the number of bytes that were actually 
copied. If reqCount is 0, no bytes are copied. The parameter dataPtr is a pointer to the data to be. 
copied to the send queue. ; 
Setting the eom parameter to a nonzero value causes a logical end-of-message indicator tobe, . ... 
inserted just after the last data byte to be written. If reqCount is 0, only the end-of-message - 


indicator is added to the send queue. 


If the flush parameter is nonzero, ADSP immediately sends this and any unsent data in the send . 
queue to the remote connection end (assuming there is buffer space at the remote end). If flush is | 
0, the data is placed in the send queue but may not be sent immediately. Details on when data is 
actually transmitted to the remote connection end can be found in “Set Options” later in this 


chapter. 


Note that bytes written to the send queue are not removed until their receipt has been 


acknowledged by the remote connection end. 


Parameter block 


Result codes 


A 
| 
SSBRBRVR 


errRefNum 
errState 
errAborted 


bad connection refnum 
connection is not open 
request aborted by a dspRemove or dspClose call 


78) 


Write bytes 


csCode word always dspWrite 

ccbRefNum —= word _ refnum of connection end wen 
reqCount word requested number of bytes to be written 
actCount word actual number of bytes written 

dataPtr long __— pointer to data to be written 

eom byte 1 if end of message; otherwise, 0 

flush byte 1 to send data now; otherwise, 0 


Nis 39H 
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Send Attention Message 


This call is used to send an attention message to the remote connection end. The attention 
message consists of a 2-byte attention code and up to 570 bytes of attention data. 

The parameter attnCode is a client-definable code sent in the attention packet. The attention 
code can contain any value from $0000 to $EFFF inclusive. Attention codes in the range from $F000 
to $FFFF inclusive are reserved by ADSP. 

The parameter attnSize specifies the number of bytes of attention data, and atinDatia is a 
pointer to the data. 

The parameter attnInterval specifies the interval between retransmissions in 10-tick (1/6- 
second) increments. The client can specify any value from 1 (1/6 second) to 180 (30 seconds, the 
connection probe frequency) inclusive. The attention is retransmitted indefinitely until it is properly 
acknowledged or the connection fails. 


Parameter block —> 2% csCode word always dspAttention 
—> 2 ccbRefNum = word __ refnum of connection end 
— 34 attnCode word _ client attention code 
—> ** attnSize word _ size in bytes of attention data 
> 8 attnData long __ pointer to attention data 
—> attnInterval byte attention retransmit interval 


Result codes errRefNum bad connection refnum 
errState connection is not open 
errAttention attention message too long 
errAborted request aborted by a dspRemove or dspClose call 
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Set Options 


This call allows the client to set options for the connection end specified by the parameter 
ccbRefNum. The send timer defines the frequency of connection-end maintenance by ADSP. At 
each timer interval, any unsent data bytes in the send queue are flushed. The timer granularity is 10 
ticks (1/6 second), and the client can set the sendTimer parameter to any value from 1 (1/6 second) 
to 180 (30 seconds, the connection probe frequency) inclusive. The default interval is 1 (1/6 second). 
Passing 0 causes the send timer to remain unchanged. 


@ Note: There are certain conditions that cause the timer interval to temporarily increase by 
multiples of itself until it reaches the frequency of the connection probe timer (30 seconds). 
This behavior is termed backing offand typically occurs when there is excessive network 
traffic. This mechanism prevents the transmission of needless, incessant packets that 
would further consume network resources. The timer returns to its normal frequency when, 
a packet is received from the remote end. 


The send blocking factor allows the client to control when packets are sent based on the 
number of unsent bytes waiting in the send queue. This feature can be useful in some applications 
in which the client requests single byte writes. By increasing the parameter sendBlocking, the client 
can reduce network traffic. Given a send blocking factor of n, ADSP sends the unsent data bytes 
only when: 


= §=The number of unsent data bytes is greater than or equal to the send blocking factor n. 
= The client has requested that all data be flushed in the Write Bytes call. 


= Some other event, such as the connection timer expiring, requires that a packet be sent to the 
remote end so any unsent data bytes will accompany the packet. 


The default blocking factor is 16 bytes, but the client can set the parameter sendBlocking to any 
value from 1 to the maximum size of a packet. Setting sendBlocking to 0 causes the factor to 
remain unchanged. 

The retransmit timer determines the number of intervals before sent, unacknowledged data in 
the send queue is retransmitted. The client can adjust the retransmit timer to adapt the connection 
to network conditions. The AppleTalk Echo Protocol (AEP) can be used to estimate round-trip 
times and to provide a gauge for setting the retransmit timer. The timer granularity is 10 ticks (1/6 
second) and the default interval is 6 (1 second). The client can set the rimtTimer parameter to any 
value from 1 (1/6 second) to 180 (30 seconds, the connection probe frequency) inclusive. Passing 0 
causes the retransmit timer to remain unchanged. 


set Options 
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The badSeqMax parameter allows the client to set the threshold for sending retransmit advice 
to the remote end. After receiving some n consecutive out-of-sequence packets, it may be more 
efficient to advise the remote end to retransmit the lost bytes than to wait for the remote end’s 
retransmit timer to expire. Setting badSeqMax to 5 causes retransmit advice to be sent to the 
remote end after 5 consecutive out-of-sequence packets have been received. badSeqMax may be set 
to any value from 1 to 255 inclusive; passing 0 causes the parameter to remain unchanged. The 
default value is 3. 

The parameter useCheckSum specifies whether DDP should compute and include a checksum in 
each packet that is sent to the remote connection end. This feature is enabled only when sending 
extended-form header DDP packets (internet packets). Regardless of the useCheckSum setting, 
ADSP automatically validates the checksum of any extended-form header DDP packet it receives 
with nonzero checksum bytes. The default for useCheckSum is FALSE. 


Parameter block —> 2% csCode word always dspOptions 

—> R ccbRefNum = word _refnum of connection end 

—> sendBlocking word _ send blocking threshold 

—> * sendTimer byte send timer interval 

—> 3 rtmtTimer byte retransmit timer interval 

—> 8 badSeqMax byte —_ retransmit advice send threshold 

—> useCheckSum byte — generate DDP checksum on internet packets 
Result codes errRefNum bad connection refnum 
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Forward Reset 


The forward-reset mechanism allows the client to flush all data written but not yet delivered to 
the remote connection end’s client. The call causes the connection end to reset its send queue and 
issue a forward-reset control packet to the remote connection end. Upon receipt of the forward- 
reset control packet, the remote connection end resets its receive queue and informs its client. 

The forward reset is nondeterministic, since all the outstanding data may have already been 
delivered to the remote client. 


Parameter block —> 2% csCode word always dspReset 

—> 32 ccbRefNum = word __refnum of connection end 
Result codes errRefNum bad connection refnum 

errState connection is not open 

errAborted request aborted by a dspRemove or dspClose call 
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Get New CID 


This call is useful for clients wanting to open a connection using an alternate means of establishing 
the two connection ends. The two clients arbitrate the connection-opening parameters using some 
alternative protocol outside the scope of ADSP. Each client informs the other of the values of its 
localCID, internet socket address, recuSeq, recvWindow, and attnRecvSeq. Each client then calls 
ADSP to synchronize the two connection ends using the parameters received from the other client. 

ADSP clients that want to utilize this connection-opening model should create their connection 
ends using the Create Connection End call. The Get New CID call then assigns a unique connection 
identifier to the connection end. This value is returned in the newCID parameter so that the client 
can pass it to the remote client. 

Once all open-connection parameters have been determined, each client calls Open Connection, 
passing ocEstablish in the ocMode parameter. 


Parameter block —> 2% csCode word always dspNewCID 
—> 22 ccbRefNum word __ refnum of connection end 
<— | newCID word new connection identifier 
Result codes errRefNum bad connection refnum 
errState connection end is not closed 
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Example 


In the following example, a client sets up a connection, writes data on it, and then closes the 


connection. 
CONST 
qSize = 600; {ample space for 512 bytes} 
myDataSize = 128; {size of my data writes} 
VAR 
error : OSErr; 
drvrRefNum : INTEGER; 
connRefNum : INTEGER; 
dspPB : DSPParamBlock; 
dspCCB : TRCCB; 


dspSendQueue : PACKED ARRAY [1..qSize] OF BYTE; 
dspRecvQueve : PACKED ARRAY [1..qSize] OF BYTE; 


dspAttnBuffer : PACKED ARRAY [1l..attnBufSize] OF BYTE; 


myData2Write : PACKED ARRAY [1..myDataSize] OF BYTE; 


BEGIN 

{make sure .MPP driver is open} 
error := MPPOpen; 

IF error <> noErr THEN Abort (error); 


{open .DSP driver} 


error := OpenDriver('.DSP', drvrRefNum) ; 
IF error <> noErr THEN Abort (error) ; 


{create a new connection end} 
WITH dspPB DO 
begin 
ioCRefNum := drvrRefNum; 
csCode := dspInit; 
ccbPtr := @dspCCB; 
userRoutine := NIL; 
sendQSize := gqSize; 
sendQueue := @dspSendQueue; 
recvQSize := qSize; 
recvQueue := @dspRecvQueue; 
attnPtr := @dspAttnBuffer; 
localSocket := 0; {dynamically allocate a socket} 
end; 
error := PBControl (@dspPB, FALSE) ; 
IF error <> noErr THEN Abort (error) ; 


connRefNum:= dspPB.ccbRefNum; {save refnum for this connection 


end} 
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{open a connection with a remote end} 
WITH dspPB DO 
begin 
ioCRefNum := drvrRefNum; 
csCode := dspOpen; 
ccbRefNum := connRefNum; 
remoteAddress := remAddress; 
filterAddress := AddrBlock (0); 


{probably used NBP to fetch remote address} 
{open connection with whoever responds} 


ocMode := ocRequest; {make an Open Connection request} 
ocInterval := 12; {retry every 2 seconds} 
ocMaximum := 5; {try 5 times before giving up} 


end; 
error := PBControl (@dspPB, FALSE) ; 
IF error <> noErr THEN Abort (error); 


{write some data on the open connection} 


WITH dspPB DO 
begin 
ioCRefNum := drvrRefNum; 
csCode := dspWrite; 
ccbRefNum := connRefNum; 
reqCount := myDataSize; {how 


many bytes to write} 


dataPtr := @myData2Write; {pointer to data to write} 
eom := 1; {end-of-message after this data} 
flush := 1; {send it now, please} 


end; 
error := PBControl(@dspPB, FALSE); 
IF error <> noErr THEN Abort (error) ; 


{close the connection and remove the 
WITH dspPB DO 
begin 
1oCRefNum := drvrRefNum; 
csCode := dspRemove; 
ccbRefNum := connRefNum; 
abort := 0; 
end; 
error := PBControl (@dspPB, FALSE) ; 
IF error <> noErr THEN Abort (error); 
END; 
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connection end} 


Appendix Summary of ADSP data structures 


THIS APPENDIX presents ADSP constants, data types, and assembly 


language information. 
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Constants 


Driver control ioResults 

errRefNum = -—-1280; {bad connection refnum} 

errAborted = -—-1279; {control call was aborted} 

errState = -1278; {bad connection state for this operation} 
errOpening = -1277; {Open Connection request failed or denied} 
errAttention = -1276; {attention message data too long} 
errFwdReset = -1275; {read terminated by forward reset} 
Driver control csCodes 

dspInit = 255; {create a new connection end} 

dspRemove = 254; {remove a connection end} 

dspOpen = 253; {open a connection} 

dspClose = 252; {close a connection} 

dspCLIinit = 251; {create a connection listener} 
dspCLRemove = 250; {remove a connection listener} 
dspCLListen = 249; {post a listener request} 

dspCLDeny = 248; {deny an Open Connection request} 
dspStatus = 247; {get status of connection end} 

dspRead = 246; {read data from the connection} 
dspWrite = 245; {write data on the connection} 
dspAttention = 244; {send an attention message} 

dspOptions = 243; {set connection end options} 

dspReset = 242; {forward reset the connection} 
dspNewCID = 241; {generate a connection identifier fora 


connection end} 


Connection-opening modes 

ocRequest = 1; {request a connection with remote} 
ocPassive = 2; {wait for a connection request from remote} 
ocAccept = 3; {accept request as delivered by listener} 
ocEstablish = 4; {consider connection to be open} 
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Connection end states 


sListening = 1; {for connection listeners} 

sPassive = 2; {waiting for a connection request from 
remote } 

sOpening = 3; {requesting a connection with remote} 

sOpen = 4; {connection is open} 

sClosing = 5; {connection is being torn down} 

sClosed = 6; {connection end state is closed} 

Client event flags 

eClosed = $80; {received connection-closed advice} 

eTearDown = $40; {closed due to broken connection} 

eAttention = $20; {received attention message} 

eFwdReset = $10; {received forward-reset advice} 

Miscellaneous constants 

attnBufSize = 570; {size of client attention buffer} 
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Data types 


Connection control block 


TPCCB = 


“TRCCB; 


TRCCB = PACKED RECORD 


ecbLink 
refnum 
state 


userFlags 


localSocket 
remoteAddress 
attnCode 
attnSize 
attnPtr 
reserved 

END; 


TPCCB; 
INTEGER; 
INTEGER; 


Byte; 


Byte; 


: AddrBlock; 


INTEGER; 
INTEGER; 
Ptr; 
ARRAY [1. 


Driver control call parameter block 


DSPPBPtr = *DSPParamBlock; 
DSPParamBlock = PACKED RECORD 
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qLink 
qlype 
1oTrap 
1oCmdAddr 
ioCompletion 
ioResult 
ioNamePtr 
ioVRefNum 
ioCRefNum 
csCode 
qStatus 
ccbRefNum 


CASE INTEGER OF 


dspInit, 

dspCLIinit: 
( 

ccbPtr 


userRoutine 


QFlemPtr; 
INTEGER; 
INTEGER; 
Ptr; 
ProcPtr; 
OSErr; 
StringPtr; 
INTEGER; 
INTEGER; 
INTEGER; 
LONGINT; 
INTEGER; 


TPCCB; 


ProcPtr; 


{link to next CCB} 


{user reference number} 


{state of the connection end} 


{user flags for unsolicited connection 


events} 


{socket number of this connection end} 


{internet address of remote end} 


{attention code received} 


{size of received attention data} 


{pointer to received attention data} 
-220] OF Byte; 


{ADSP driver 


{for ADSP internal use only} 


refnum} 


{ADSP driver control code} 


{for ADSP internal use only} 
{refnum of CCB} 


{pointer to CCB} 


{client routine to call on event} 
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sendQSize 
sendQueue 
recvQSize 
recvQueue 
attnPtr 
localSocket 
); 


dspOpen, 
dspCLListen, 
dspCLDeny: 

( 

localCID 


remoteCID 


remoteAddress 


filterAddress 


sendSeq 
sendWindow 
recvSeq 
attnSendSeq 
attnRecvSeq 
ocMode 
ocInterval 
ocMaximum 


); 


dspClose, 
dspRemove: 
( 

abort 


); 
dspStatus: 


( 
statusCCB 


sendQPending 
sendQFree 
recvQPending 


recvQFree 


INTEGER; 
Ptr; 
INTEGER; 
Ptr; 
Ptr; 


Byte; 


INTEGER; 
INTEGER; 


AddrBlock; 
AddrBlock; 


LONGINT; 
INTEGER; 
LONGINT; 
LONGINT; 
LONGINT; 
Byte; 
Byte; 
Byte; 


Byte; 


TPCCB; 

INTEGER; 
INTEGER; 
INTEGER; 
INTEGER; 


{size of send queue (0..64K bytes) } 
{client passed send queue buffer} 

{size of receive queue (0..64K bytes) } 
{client passed receive queue buffer} 
{client passed receive attention buffer} 


{local socket number} 


{local connection identifier} 
{remote connection identifier} 
{address of remote end} 

{address filter} 

{local send sequence number} 

{send window size} 

{receive sequence number} 
{attention send sequence number} 
{attention receive sequence number} 
{open-connection mode} 

{Open Connection request retry interval} 


{Open Connection request retry maximum} 


{abort connection immediately if 


nonzero} 


{pointer to CCB} 

{pending bytes in send queue} 
{available buffer space in send queue} 
{pending bytes in receive queue} 
{available buffer space in receive 


queue} 
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dspRead, 
dspWrite: 
( 
reqCount 
actCount 
dataPtr 
eom 
flush 


); 


dspAttention: 


( 

attnCode 
attnSize 
attnData 
attnIinterval 


); 


dspOptions: 
( 
sendBlocking 
sendTimer 
rtmtTimer 
badSeqMax 


useCheckSum 


); 


dspNewCID: 
( 

newCID 

); 

END; 


INTEGER; 
INTEGER; 
Ptr; 
Byte; 
Byte; 


INTEGER; 
INTEGER; 
Ptr; 
Byte; 


INTEGER; 
Byte; 
Byte; 
Byte; 


Byte; 


INTEGER; 


{requested number of bytes} 
{actual number of bytes} 

{pointer to data buffer} 
{indicates logical end of message} 


{send data now} 


{client attention code} 
{size of attention data} 
{pointer to attention data} 


{retransmit timer in 10-tick intervals} 


{quantum for data packets} 

{send timer in 10-tick intervals} 
{retransmit timer in 10-tick intervals} 
{threshold for sending retransmit 
advice} 

{send checksum in extended-form header 
DDP packets} 


{new connection identifier returned} 
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Assembly language information 


error codes 


errRefNum 
errAborted 
errState 


errOpening 


errAttention 


errFwdReset 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


-1280 
-1279 
-1278 
-1277 
-1276 
-1275 


client control codes 


dspInit 
dspRemove 
dspOpen 
dspClose 
dspCLIinit 
dspCLRemove 
dspCLListen 
dspCLDeny 
dspStatus 
dspRead 
dspWrite 


dspAttention 


dspOptions 
dspReset 
dspNewCID 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


open connection 


ocRequest 
ocPassive 
ocAccept 
ocEstablish 


EQU 
EQU 
EQU 
EQU 


255 
254 
253 
252 
251 
250 
249 
248 
247 
246 
245 
244 
243 
242 
241 


modes 


& W BR F 


connection states 


sListening 
sPassive 
sOpening 
sOpen 
sClosing 
sClosed 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


aA oO & WwW DH FH 


we 


e 
a’ 


bad connection refnum 

control call was aborted 

bad connection state for this operation 
Open Connection request failed or denied 
attention message data too long 


read terminated by forward reset 


create a new connection end 
remove a connection end 

open a connection 

close a connection 

create a connection listener 
remove a connection listener 
post a listener request 

deny an Open Connection request 
get status of connection end 
read data from the connection 
write data on the connection 
send an attention message 

set connection end options 
forward reset the connection 


generate a connection identifier for a 


connection end 


.e 


we 


request a connection with remote 
walt for a connection request from remote 
accept request as delivered by listener 


consider connection to be open 


for connection listeners 

waiting for a connection request from remote 
requesting a connection with remote 
connection is open 

connection is being torn down 


connection end state is closed 
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client event flags 


eClosed EQU 
eTearDown EQU 
eAttention EQU 
eFwdReset EQU 


(bit-mask) 
$80 ; 
$40 ; 
$20 ; 
$10 ; 


miscellaneous equates 


attnBufSize EQU 


connection control 


ccbLink EQU 
refnum EQU 
state EQU 
userFlags EQU 
localSocket EQU 
remoteAddress EQU 
attnCode EQU 
attnSize EQU 
attnPtr EQU 
ccbSize EQU 
adsp queue element 
csQStatus EQU 
csCCBRef EQU 
dspInit, dspCLIinit 
ecsCCBPtr EQU 
csUserRtn EQU 
csSendQSize EQU 
csSendQueue EQU 
csRecvQSize EQU 
csRecvQueue EQU 
csAttnPtr EQU 
csLocSkt EQU 
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570 ; 


received connection-closed advice 
closed due to broken connection 
received attention message 


received forward-reset advice 


size of client attention message 


block equates & size 


0 
ecbLink+4 
refnumt+2 


statet+2 


userFlags+1l 
localSocket+1. 
remoteAddress+4 
attnCodet2 
attnSizet2 
attnPtrt+224 


equates 


CSParam 


csQStatust4 


csCCBRef+2 
csCCBPtr+4 
csUserRtnt4 
csSendQSizet2 
csSendQueuet4 
csRecvQSize+2 


csRecvQueuet4 


csAttnPtrt+4 


e 
a? 


link to next CCB 
user reference number 
state of the connection end 


flags for unsolicited connection 


events 


we 


ve 


we we we 


=e 


eo 
o 
e 
ao 


e 
td 


socket number of this connection end 
internet address of remote end 
attention code received 

size of received attention data 
pointer to received attention data 
total byte size of CCB 


for ADSP internal use only 
refnum of CCB 


pointer to CCB 

client routine to call on event 
size of send queve (0..64K bytes) 
client passed send queue buffer 
size of receive queue (0..64K bytes) 
client passed receive queue buffer 


client passed receiving attention 


buffer 


local socket number 
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dspOpen, dspCLListen, dspCLDeny 


csLocCID EQU csCCBRef+2 
csRemCID EQU csLocCID+2 
csRemAddr EQU csRemCID+2 
csFltrAddr EQU csRemAddr+4 
csSendSeq EQU cesFltrAddr+4 
cesSendWdw EQU esSendSeq+4 
csRecvSeq EQU csSendWdwt+2 
csAttnSendSeq EQU csRecvSeq+4 
csAttnRecvSeq EQU csAttnSendSeqt4 
csOCMode EQU csAttnRecvSeqt4 
csOCInterval EQU csOCModetl 
csOCMaximum EQU csOCInterval+l 
dspClose, dspRemove 
csAbort EQU csCCBRef+2 
dspStatus 
csSQPending EQU csCCBPtr+4 
csSQF ree EQU csSQPending+2 
csRQPending EQU csSQFree+2 
csROFree EQU csRQPendingt2 
dspRead, dspWrite 
csReqCount EQU csCCBRef+2 
csActCount EQU csReqCount+2 
csDataPtr EQU csActCount+2 
csEOM EQU csDataPtr+4 
csFlush EQU csEOM+1 
dspAttention 
csAttnCode EQU csCCBRef+2 
csAttnSize EQU csAttnCode+2 
csAttnData EQU csAttnSizet+2 
csAttnInterval EQU csAttnDatat4 


eo 
o 


local connection identifier 
remote connection identifier 
address of remote end 

address filter 

local send sequence number 

send window size 

receive sequence number 

attention send sequence number 
attention receive sequence number 
open-connection mode 

Open Connection request retry interval 


Open Connection request retry maximum 


abort connection immediately if 


nonzero 


we 


pending bytes in send queue 
available buffer space in send queue 
pending bytes in receive queue 


available buffer space in receive 


queue 


we we we we 


we 


‘we ve we 


ve 


requested number of bytes 

actual number of bytes 

pointer to data buffer 

indicates logical end of message 


send data now 


client attention code 
size of attention data 
pointer to attention data 


retransmit timer in 10-tick intervals 
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dspOptions 


csSendBlocking EQU 


cesSendTimer EQU 
csRtmtTimer EQU 
csBadSeqMax EQU 


csUseCheckSum EQU 


dspNewCID 


csNewCID EQU 
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csCCBRef+2 
csSendBlocking+2 
csSendTimert+l 
csRtmtTimer+l 


csBadSeqMaxtl 


csCCBRef+2 


quantum for data packets 
send timer in 10-tick intervals 
retransmit timer in 10-tick intervals 


threshold for sending retransmit 


advice 


e 
a’ 


use DDP packet checksum 


new connection identifier returned 


